

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  
  <title>Ceph 文档中文翻译说明 &mdash; Ceph Documentation</title>
  

  
  <link rel="stylesheet" href="../_static/ceph.css" type="text/css" />
  <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../_static/ceph.css" type="text/css" />
  <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" />
  <link rel="stylesheet" href="../_static/css/custom.css" type="text/css" />

  
  

  
  

  

  
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
    
      <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
        <script src="../_static/jquery.js"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
        <script src="../_static/doctools.js"></script>
        <script src="../_static/sphinx_highlight.js"></script>
    
    <script type="text/javascript" src="../_static/js/theme.js"></script>

    
    <link rel="index" title="Index" href="../genindex/" />
    <link rel="search" title="Search" href="../search/" /> 
</head>

<body class="wy-body-for-nav">

   
  <header class="top-bar">
    <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../" class="icon icon-home" aria-label="Home"></a></li>
      <li class="breadcrumb-item active">Ceph 文档中文翻译说明</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../_sources/README.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
  </header>
  <div class="wy-grid-for-nav">
    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search"  style="background: #eee" >
          

          
            <a href="../" class="icon icon-home"> Ceph
          

          
          </a>

          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search/" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        
        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul>
<li class="toctree-l1"><a class="reference internal" href="../start/">Ceph 简介</a></li>
<li class="toctree-l1"><a class="reference internal" href="../install/">安装 Ceph</a></li>
<li class="toctree-l1"><a class="reference internal" href="../cephadm/">Cephadm</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rados/">Ceph 存储集群</a></li>
<li class="toctree-l1"><a class="reference internal" href="../cephfs/">Ceph 文件系统</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rbd/">Ceph 块设备</a></li>
<li class="toctree-l1"><a class="reference internal" href="../radosgw/">Ceph 对象网关</a></li>
<li class="toctree-l1"><a class="reference internal" href="../mgr/">Ceph 管理器守护进程</a></li>
<li class="toctree-l1"><a class="reference internal" href="../mgr/dashboard/">Ceph 仪表盘</a></li>
<li class="toctree-l1"><a class="reference internal" href="../monitoring/">监控概览</a></li>
<li class="toctree-l1"><a class="reference internal" href="../api/">API 文档</a></li>
<li class="toctree-l1"><a class="reference internal" href="../architecture/">体系结构</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev/developer_guide/">开发者指南</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev/internals/">Ceph 内幕</a></li>
<li class="toctree-l1"><a class="reference internal" href="../governance/">项目管理</a></li>
<li class="toctree-l1"><a class="reference internal" href="../foundation/">Ceph 基金会</a></li>
<li class="toctree-l1"><a class="reference internal" href="../ceph-volume/">ceph-volume</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releases/general/">Ceph 版本（总目录）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releases/">Ceph 版本（索引）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security/">Security</a></li>
<li class="toctree-l1"><a class="reference internal" href="../hardware-monitoring/">硬件监控</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary/">Ceph 术语</a></li>
<li class="toctree-l1"><a class="reference internal" href="../jaegertracing/">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../translation_cn/">中文版翻译资源</a></li>
</ul>

            
          
        </div>
        
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../">Ceph</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content">
        
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
<div id="dev-warning" class="admonition note">
  <p class="first admonition-title">Notice</p>
  <p class="last">This document is for a development version of Ceph.</p>
</div>
  <div id="docubetter" align="right" style="padding: 5px; font-weight: bold;">
    <a href="https://pad.ceph.com/p/Report_Documentation_Bugs">Report a Documentation Bug</a>
  </div>

  
  <section id="ceph">
<h1>Ceph 文档中文翻译说明<a class="headerlink" href="#ceph" title="Permalink to this heading"></a></h1>
<p>This is Chinese translation of Ceph distributed storage system documents
(mainly <code class="docutils literal notranslate"><span class="pre">doc</span></code> and <code class="docutils literal notranslate"><span class="pre">src/common/options/*yaml.in</span></code>, from <a class="reference external" href="https://github.com/ceph/ceph">https://github.com/ceph/ceph</a>),
the translation tooling suits for any language, maybe :-D, you are allowed to
reuse them for your translation, just let me known,
email me &lt;<a class="reference external" href="mailto:gongfan193&#37;&#52;&#48;gmail&#46;com">gongfan193<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt;</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="m">22</span>:29:30<span class="w"> </span>~/ceph-Chinese-doc<span class="w"> </span>$<span class="w"> </span>./qa

Progress<span class="w"> </span>by<span class="w"> </span>subsys:
<span class="w">    </span>start/<span class="w">                </span><span class="m">91</span>.17%
<span class="w">    </span>install/<span class="w">              </span><span class="m">76</span>.39%
<span class="w">    </span>rados/<span class="w">                </span><span class="m">70</span>.14%
<span class="w">    </span>radosgw/<span class="w">              </span><span class="m">55</span>.82%
<span class="w">    </span>rbd/<span class="w">                  </span><span class="m">63</span>.35%
<span class="w">    </span>cephfs/<span class="w">               </span><span class="m">100</span>.0%
<span class="w">    </span>man/<span class="w">                  </span><span class="m">100</span>.0%
<span class="w">    </span>cephadm/<span class="w">              </span><span class="m">21</span>.84%
<span class="w">    </span>ceph-volume/<span class="w">          </span><span class="m">27</span>.52%
<span class="w">    </span>mgr/<span class="w">                  </span><span class="m">27</span>.05%
<span class="w">    </span>monitoring/<span class="w">           </span><span class="m">100</span>.0%
<span class="w">    </span>hardware-monitoring/<span class="w">  </span><span class="m">100</span>.0%
<span class="w">    </span>jaegertracing/<span class="w">        </span><span class="m">34</span>.38%
<span class="w">    </span>security/<span class="w">             </span><span class="m">23</span>.5%
Overall<span class="w"> </span>progress:<span class="w">   </span><span class="m">65</span>.5%<span class="w"> </span><span class="o">(</span><span class="m">11935</span><span class="w"> </span>of<span class="w"> </span><span class="m">34594</span><span class="w"> </span>rows<span class="w"> </span>to<span class="w"> </span>translate<span class="o">)</span>
</pre></div>
</div>
<hr class="docutils" />
<p>这里是 Ceph 文档中文版的源码，编译好的位于：
<a class="reference external" href="https://github.com/drunkard/ceph-readable-doc">https://github.com/drunkard/ceph-readable-doc</a> ，可以克隆到本地，启动HTTP服务，
直接飞速浏览。</p>
<section id="id1">
<h2>中文版文档风格<a class="headerlink" href="#id1" title="Permalink to this heading"></a></h2>
<p>译文的语言风格：</p>
<ul class="simple">
<li><p>通俗易懂，尽量不用生僻的词语，前人没有翻译过的术语、又不太好直译的，想办法用转义、通感之类的修辞方法翻译；</p></li>
<li><p>尽量用本土化的语言风格；中文就按汉语习惯翻译，不做直译，有时候反而不好理解；</p></li>
<li><p>废话少说，捞干的。</p></li>
</ul>
<p>词语的翻译应该尽量一致，请参考<a class="reference external" href="/translation_cn/translation-convention">翻译惯例</a>（即 translation-convention.rst ）。</p>
<p>尽量遵守原文档的书写风格，如缩进、不超过 80 列宽、等。</p>
<p>有些风格是中文版特有的，如：</p>
<ul>
<li><p>中文和非中文用空格分隔；</p></li>
<li><p>插入命令，前一段行尾加空格和双引号（” ::”），否则编译器不能正确识别；</p></li>
<li><p>尽量保留原文的标题、并改为注释或链接，以防别的文档里有（自动生成的）引用，且便于后续更新；如果链接与别的冲突了，可改为注释（行首加两点和空格）；</p></li>
<li><p>用反斜线（”\”）换行，这样不会额外增加空格，即不留白；</p></li>
<li><p>原文中用双引号引用的词语在中文文档里可去掉引号，因为原文引用它已经很显眼了；</p></li>
<li><p>断行考虑因素：</p>
<blockquote>
<div><ul class="simple">
<li><p>为防止中文版和英文版文档的行数差得太多、在后续更新时找不到位置，中文版断行要提前，比如在 64 列左右断行；</p></li>
<li><p><strong>断行列数要与 vi_two_files.sh 脚本内的一致；</strong></p></li>
<li><p>断行尽量避开词语、术语，后续要批量更改的时候方便用 <code class="docutils literal notranslate"><span class="pre">grep</span></code> 过滤；</p></li>
<li><p>尽量按语义断行，即语义所在行和原文基本一致，语义一致时不必太在意列是否整齐，反正编译后会合并成一行；好处也是方便用 <code class="docutils literal notranslate"><span class="pre">grep</span></code> 过滤。</p></li>
</ul>
</div></blockquote>
</li>
</ul>
</section>
<section id="id3">
<h2>翻译流程<a class="headerlink" href="#id3" title="Permalink to this heading"></a></h2>
<p>下面大致是一个完整的工作流程。</p>
<section id="id4">
<h3>先是配置环境<a class="headerlink" href="#id4" title="Permalink to this heading"></a></h3>
<ol class="arabic">
<li><p>配置 Python venv 环境。</p>
<p>用于辅助翻译质量的工具 <code class="docutils literal notranslate"><span class="pre">qa</span></code> 是用 Python 写的，主要用了 <code class="docutils literal notranslate"><span class="pre">pandas</span></code> ，
我这里配置了 venv 环境配置:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python3</span><span class="mf">.9</span> <span class="o">-</span><span class="n">m</span> <span class="n">venv</span> <span class="o">/</span><span class="n">cc</span>
<span class="o">.</span> <span class="o">/</span><span class="n">cc</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">activate</span>
<span class="n">pip</span> <span class="n">install</span> <span class="n">pandas</span>
</pre></div>
</div>
</li>
<li><p>把代码库复制到本地，然后才能开始翻译、编译文档。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mkdir</span> <span class="o">/</span><span class="n">git</span> <span class="o">&amp;&amp;</span> <span class="n">cd</span> <span class="o">/</span><span class="n">git</span>
<span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">ceph</span><span class="o">/</span><span class="n">ceph</span><span class="o">.</span><span class="n">git</span>
<span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="p">{</span><span class="n">你的github用户名</span><span class="p">}</span><span class="o">/</span><span class="n">ceph</span><span class="o">-</span><span class="n">Chinese</span><span class="o">-</span><span class="n">doc</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
</li>
<li><p>配置环境，做软链接，否则编译可能会出错。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="o">/</span><span class="n">git</span><span class="o">/</span><span class="n">ceph</span>
<span class="n">ln</span> <span class="o">-</span><span class="n">s</span> <span class="o">/</span><span class="n">git</span><span class="o">/</span><span class="n">ceph</span><span class="o">-</span><span class="n">Chinese</span><span class="o">-</span><span class="n">doc</span> <span class="n">doc</span><span class="o">-</span><span class="n">zh</span>

<span class="n">cd</span> <span class="o">/</span><span class="n">git</span><span class="o">/</span><span class="n">ceph</span><span class="o">/</span><span class="n">admin</span>
<span class="n">ln</span> <span class="o">-</span><span class="n">sf</span> <span class="o">../</span><span class="n">doc</span><span class="o">-</span><span class="n">zh</span><span class="o">/</span><span class="n">translation_cn</span><span class="o">/</span><span class="n">zh_build</span><span class="o">-</span><span class="n">doc</span> <span class="o">.</span>
<span class="n">ln</span> <span class="o">-</span><span class="n">sf</span> <span class="o">../</span><span class="n">doc</span><span class="o">-</span><span class="n">zh</span><span class="o">/</span><span class="n">translation_cn</span><span class="o">/</span><span class="n">zh_serve</span><span class="o">-</span><span class="n">doc</span> <span class="n">serve</span><span class="o">-</span><span class="n">doc_zh</span>
</pre></div>
</div>
</li>
</ol>
</section>
<section id="id5">
<h3>然后开始翻译<a class="headerlink" href="#id5" title="Permalink to this heading"></a></h3>
<p>本项目的更新有两种：</p>
<ol class="arabic simple">
<li><p>对照着 Ceph 项目源码内与 doc/ 目录相关的 git commit ，把文档里变更过的部分同步到本项目的对应文件；</p></li>
<li><p>根据本项目脚本 ./qa 的输出结果，选择自己喜欢的子系统、文件进行翻译。</p></li>
</ol>
<p>我写了个翻译辅助脚本，通过 deepl.com 翻译每一个段落，用法：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">./</span><span class="n">translation_cn</span><span class="o">/</span><span class="n">online_translate</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">h</span>
</pre></div>
</div>
<p>下面会分别介绍各自的流程。</p>
<section id="git-commit">
<h4>按 git commit 更新<a class="headerlink" href="#git-commit" title="Permalink to this heading"></a></h4>
<p>以下只是大致步骤，路径不同时还需修改脚本。</p>
<ol class="arabic">
<li><p>执行 <code class="docutils literal notranslate"><span class="pre">update-doc.sh</span></code> 脚本，可以看到接下来需要同步的 git commit 历史。这个脚本用到了 <code class="docutils literal notranslate"><span class="pre">git</span></code> 和 <code class="docutils literal notranslate"><span class="pre">tig</span></code> 命令，最好先检查下安装了没。</p>
<p>对照着 tig 里的 commit 历史开始更新中文文档！</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="o">/</span><span class="n">git</span><span class="o">/</span><span class="n">ceph</span><span class="o">-</span><span class="n">Chinese</span><span class="o">-</span><span class="n">doc</span><span class="o">/</span> <span class="o">&amp;&amp;</span> <span class="o">./</span><span class="n">translation_cn</span><span class="o">/</span><span class="n">update</span><span class="o">-</span><span class="n">doc</span><span class="o">.</span><span class="n">sh</span>
</pre></div>
</div>
</li>
<li><p>必须按日期更新！！！一次最少要更新一天的。如果遇上 commit 历史交叉得厉害，
可能一次必须更新很多天的。</p>
<p>更新完这一批后，需要更改脚本 <code class="docutils literal notranslate"><span class="pre">env.sh</span></code> 里的 <code class="docutils literal notranslate"><span class="pre">SYNC_TO</span></code> 变量。
日期需要自己计算，下一个日期是当前的日期加下面 <code class="docutils literal notranslate"><span class="pre">STEP</span></code> 的天数。比如：现在是
<code class="docutils literal notranslate"><span class="pre">SYNC_TO=&quot;2022-01-05&quot;</span></code> ，而且 <code class="docutils literal notranslate"><span class="pre">STEP=7</span></code> ，那么下一个 <code class="docutils literal notranslate"><span class="pre">SYNC_TO</span></code> 就应该是
<code class="docutils literal notranslate"><span class="pre">2022-01-12</span></code> 。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vi</span> <span class="n">env</span><span class="o">.</span><span class="n">sh</span>
<span class="c1"># 更改 SYNC_TO 变量，日期格式不要变</span>
</pre></div>
</div>
</li>
<li><p>翻译完、核对完之后，用 <code class="docutils literal notranslate"><span class="pre">commit-updated.sh</span></code> 脚本提交（如果你用
<code class="docutils literal notranslate"><span class="pre">zh_build-doc</span></code> 编译了中文文档，
这个脚本也会自动同步编译后的库，如果没有就只是提交当前库）:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">./</span><span class="n">translation_cn</span><span class="o">/</span><span class="n">commit</span><span class="o">-</span><span class="n">updated</span><span class="o">.</span><span class="n">sh</span>
</pre></div>
</div>
</li>
</ol>
</section>
<section id="qa">
<h4>按 qa 脚本的指引翻译<a class="headerlink" href="#qa" title="Permalink to this heading"></a></h4>
<ol class="arabic">
<li><p>先看看这个项目的翻译情况：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="o">/</span><span class="n">git</span><span class="o">/</span><span class="n">ceph</span><span class="o">-</span><span class="n">Chinese</span><span class="o">-</span><span class="n">doc</span><span class="o">/</span>

<span class="c1"># 看整个项目的翻译情况</span>
<span class="o">./</span><span class="n">qa</span>

<span class="c1"># 看单个子系统的翻译情况（不含 ``dev/`` ，开发文档）</span>
<span class="o">./</span><span class="n">qa</span> <span class="n">rbd</span>

<span class="c1"># 看单个文档的翻译情况</span>
<span class="o">./</span><span class="n">qa</span> <span class="n">rbd</span><span class="o">/</span><span class="n">rbd</span><span class="o">-</span><span class="n">mirroring</span><span class="o">.</span><span class="n">rst</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">qa</span></code> 工具的输出仅作参考，应该能够涵盖大部分应该翻译的内容。</p>
</li>
</ol>
</section>
</section>
<section id="id6">
<h3>翻译的注意事项<a class="headerlink" href="#id6" title="Permalink to this heading"></a></h3>
<p>ditaa 图还不能翻译为中文，因为渲染时的字体问题还未解决。</p>
<p>配置选项的翻译特殊，不同于常规文档翻译，单独介绍：</p>
<section id="id7">
<h4>配置选项的翻译<a class="headerlink" href="#id7" title="Permalink to this heading"></a></h4>
<p>原文档的配置选项用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">confval::</span></code> 来解释含义，源文件位于 <code class="docutils literal notranslate"><span class="pre">src/common/options/*.yaml.in</span></code> 里。为翻译这部分内容，我把它们复制到了 <code class="docutils literal notranslate"><span class="pre">zh_options/</span></code> 里面，只需翻译描述部分，字段名不能改，否则渲染系统就识别不到了，也就是说， <code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">|</span> <span class="pre">default</span> <span class="pre">|</span> <span class="pre">min</span> <span class="pre">|</span> <span class="pre">max</span></code> 之类的字段名只能维持原样，不能像原来一样翻译成 <code class="docutils literal notranslate"><span class="pre">类型</span> <span class="pre">|</span> <span class="pre">默认值</span> <span class="pre">|</span> <span class="pre">最小值</span> <span class="pre">|</span> <span class="pre">最大值</span></code> 。</p>
<p>此外，还需更改 <code class="docutils literal notranslate"><span class="pre">*.yaml.in</span></code> 文件的路径，让渲染系统采用译文：</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># conf.py -&gt; ceph_confval_imports ，需要改成 doc-zh/zh_options</span>

<span class="w"> </span><span class="nv">ceph_confval_imports</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>glob.glob<span class="o">(</span>os.path.join<span class="o">(</span>top_level,
-<span class="w">                                              </span><span class="s1">&#39;doc-zh/zh_options&#39;</span>,
+<span class="w">                                              </span><span class="s1">&#39;src/common/options&#39;</span>,
<span class="w">                                               </span><span class="s1">&#39;*.yaml.in&#39;</span><span class="o">))</span>
</pre></div>
</div>
<section id="desc">
<h5>desc<a class="headerlink" href="#desc" title="Permalink to this heading"></a></h5>
<p>yaml.in 文件里同时有 fmt_desc|long_desc|desc 时，优先级为
fmt_desc &gt; long_desc &gt; desc ，见 _ext/ceph_confval.py 里：</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">desc</span> <span class="o">=</span> <span class="n">opt</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;fmt_desc&#39;</span><span class="p">)</span> <span class="ow">or</span> <span class="n">opt</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;long_desc&#39;</span><span class="p">)</span> <span class="ow">or</span> <span class="n">opt</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;desc&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>注意：字段内容不能以 ‘`’ 打头，编译器会报错。</p>
</section>
<section id="id8">
<h5>字段名<a class="headerlink" href="#id8" title="Permalink to this heading"></a></h5>
<p>TODO: 翻译字段名，位于 _ext/ceph_confval.py -&gt; TEMPLATE</p>
</section>
</section>
</section>
<section id="id9">
<h3>翻译后，测试下编译是否有报错<a class="headerlink" href="#id9" title="Permalink to this heading"></a></h3>
<p>编译是为了看看还有没有什么问题。如果有报错，最好编译一下原版的文档，
对比一下出错的地方，有些错误原文里就有，修正需要的工作量较大。</p>
<ol class="arabic">
<li><p>编译环境配置。</p>
<ul class="simple">
<li><p>在系统内安装 <code class="docutils literal notranslate"><span class="pre">ceph</span></code> 软件，编译文档前脚本会自动配置文档的编译环境，配置时依赖随 <code class="docutils literal notranslate"><span class="pre">ceph</span></code> 安装的库，这个依赖是一次性的，文档能正常编译之后就可以删掉安装的 <code class="docutils literal notranslate"><span class="pre">ceph</span></code> 软件。</p></li>
<li><p>在系统内安装 <code class="docutils literal notranslate"><span class="pre">ditaa</span></code> ，编译文档里的 ditaa 图需要这个软件。它依赖
Java 虚拟机，应该用 JDK，比如 oracle-jdk-bin-1.8 或 oracle-jdk-bin-1.7 ，
jre 缺少必要的库文件。</p></li>
<li><p>安装 Sphinx ，这个文档编译系统是基于 Python 的，我现在用的是 Python 3.11 ；</p></li>
</ul>
</li>
<li><p>执行 ceph 代码库内的 <code class="docutils literal notranslate"><span class="pre">admin/build-doc</span></code> 开始构建文档；</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># 编译原版文档</span>
./admin/build-doc

<span class="c1"># 编译中文版文档</span>
<span class="nb">cd</span><span class="w"> </span>/git/ceph<span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span>mkdir<span class="w"> </span>doc-zh/
mount<span class="w"> </span>--bind<span class="w"> </span>/git/ceph-Chinese-doc<span class="w"> </span>doc-zh<span class="w">     </span><span class="c1"># 需要 root 权限</span>
./admin/zh_build-doc
./admin/zh_build-doc<span class="w"> </span>linkcheck<span class="w">    </span><span class="c1"># 检查链接是否有效，耗时很长</span>
</pre></div>
</div>
<p>解释：为何要创建 <code class="docutils literal notranslate"><span class="pre">/git/ceph/doc-zh/</span></code> 目录并挂载呢，软链接行不行？软链接有时候可以，有时候脚本里有 <cite>realpath</cite> ，会导致计算出的路径出现偏差，进而导致文档编译错误。所以，还是挂载更稳定。</p>
<p>注意：脚本在正式编译前，会自动在 <code class="docutils literal notranslate"><span class="pre">/git/ceph/build-doc/</span></code> 下配置编译所需的python venv 环境。其中， <code class="docutils literal notranslate"><span class="pre">pip</span></code> 在安装 <code class="docutils literal notranslate"><span class="pre">/git/ceph/admin/doc-pybind.txt</span></code>
时，可能会遇到编译失败的情况，这个不解决就无法编译文档。一个临时解决方法是：在系统内安装 ceph 时已经装过对应的 python binding 了，可以把那些装好的库复制到 venv 下，以 <code class="docutils literal notranslate"><span class="pre">rados</span></code> 模块为例：</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>.<span class="w"> </span>/git/ceph/build-doc/virtualenv/bin/activate
pip<span class="w"> </span>list<span class="w">      </span><span class="c1"># 此时应该没有 rados 模块</span>

<span class="nb">cd</span><span class="w"> </span>/usr/lib/python3.12/site-packages
cp<span class="w"> </span>-r<span class="w"> </span>rados*<span class="w"> </span>/git/ceph/build-doc/virtualenv/lib/python3.12/site-packages/

pip<span class="w"> </span>list<span class="w">      </span><span class="c1"># 此时有 rados 模块</span>
</pre></div>
</div>
</li>
<li><p>启动文档服务器，这样就可以通过 <a class="reference external" href="http://localhost:9080/">http://localhost:9080/</a> 阅读文档了。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="o">/</span><span class="n">git</span><span class="o">/</span><span class="n">ceph</span>
<span class="o">./</span><span class="n">admin</span><span class="o">/</span><span class="n">serve</span><span class="o">-</span><span class="n">doc_zh</span>    <span class="c1"># 在 http://localhost:9080/ 看中文版文档</span>

<span class="o">./</span><span class="n">admin</span><span class="o">/</span><span class="n">serve</span><span class="o">-</span><span class="n">doc</span>       <span class="c1"># 在 http://localhost:8080  看原版文档</span>
</pre></div>
</div>
</li>
</ol>
<p>如果编译失败，请参考<a class="reference external" href="/translation_cn/build-errors">此文档</a>（即 build-errors.rst ）解决。</p>
<p>编译没问题的话，可以在 github 上向我反馈您的更新，比如 <cite>pull request</cite> :-)</p>
</section>
</section>
</section>



<div id="support-the-ceph-foundation" class="admonition note">
  <p class="first admonition-title">Brought to you by the Ceph Foundation</p>
  <p class="last">The Ceph Documentation is a community resource funded and hosted by the non-profit <a href="https://ceph.io/en/foundation/">Ceph Foundation</a>. If you would like to support this and our other efforts, please consider <a href="https://ceph.io/en/foundation/join/">joining now</a>.</p>
</div>


           </div>
           
          </div>
          <footer>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2016, Ceph authors and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0).</p>
  </div>

   

</footer>
        </div>
      </div>

    </section>

  </div>
  

  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

  
  
    
   

</body>
</html>